.TH LS 1 "GNU File Utilities" "FSF" \" -*- nroff -*-
.SH NAME
ls, dir, vdir \- list contents of directories
.SH SYNOPSIS
.B ls
[\-abcdfgiklmnpqrstuxABCFGLNQRSUX1] [\-w cols] [\-T cols] [\-I pattern]
[\-\-all] [\-\-escape] [\-\-directory] [\-\-inode] [\-\-kilobytes]
[\-\-numeric-uid-gid] [--no-group] [\-\-hide-control-chars] [\-\-reverse]
[\-\-size] [\-\-width=cols] [\-\-tabsize=cols] [\-\-almost-all]
[\-\-ignore-backups] [\-\-classify] [\-\-file-type] [\-\-full-time]
[\-\-ignore=pattern] [\-\-dereference] [\-\-literal] [\-\-quote-name]
[\-\-recursive] [\-\-sort={none,time,size,extension}]
[\-\-format={long,verbose,commas,across,vertical,single-column}]
[\-\-time={atime,access,use,ctime,status}] [\-\-help] [\-\-version]
[\-\-color[={yes,no,tty}]] [\-\-colour[={yes,no,tty}]] [name...]
.SH DESCRIPTION
This documentation is no longer being maintained and may be inaccurate
or incomplete.  The Texinfo documentation is now the authoritative source.
.PP
This manual page
documents the GNU version of
.BR ls .
.B dir
and
.B vdir
are versions of
.B ls
with different default output formats.
These programs list each given file or directory name.  Directory contents are
sorted alphabetically.  For
.BR ls ,
files are by default listed in columns, sorted
vertically, if the standard output is a terminal; otherwise they are
listed one per line.  For
.BR dir ,
files are by default listed in columns, sorted vertically.  For
.BR vdir ,
files are by default listed in long format.
.SS OPTIONS
.TP
.I "\-a, \-\-all"
List all files in directories, including all files that start with `.'.
.TP
.I "\-b, \-\-escape"
Quote nongraphic characters in file names using alphabetic and octal
backslash sequences like those used in C.
.TP
.I "\-c, \-\-time=ctime, \-\-time=status"
Sort directory contents according to the files' status change time
instead of the modification time.  If the long listing format is being
used, print the status change time instead of the modification time.
.TP
.I "\-d, \-\-directory"
List directories like other files, rather than listing their contents.
.TP
.I "\-f"
Do not sort directory contents; list them in whatever order they are
stored on the disk.
The same as enabling
.I \-a
and
.I \-U
and disabling
.I \-l,
.I \-s,
and
.I \-t.
.TP
.I "\-\-full-time"
List times in full, rather than using the standard abbreviation
heuristics.
.TP
.I \-g
Ignored; for Unix compatibility.
.TP
.I "\-i, \-\-inode"
Print the index number of each file to the left of the file name.
.TP
.I "\-k, \-\-kilobytes"
If file sizes are being listed, print them in kilobytes.  This
overrides the environment variable POSIXLY_CORRECT.
.TP
.I "\-l, \-\-format=long, \-\-format=verbose"
In addition to the name of each file, print the file type,
permissions, number of hard links, owner name, group name, size in
bytes, and timestamp (the modification time unless other times are
selected).  For files with a time that is more than 6 months old or
more than 1 hour into the future, the timestamp contains the year
instead of the time of day.
.TP
.I "\-m, \-\-format=commas"
List files horizontally, with as many as will fit on each line,
separated by commas.
.TP
.I "\-n, \-\-numeric-uid-gid"
List the numeric UID and GID instead of the names.
.TP
.I \-p
Append a character to each file name indicating the file type.
.TP
.I "\-q, \-\-hide-control-chars"
Print question marks instead of nongraphic characters in file names.
.TP
.I "\-r, \-\-reverse"
Sort directory contents in reverse order.
.TP
.I "\-s, \-\-size"
Print the size of each file in 1K blocks to the left of the file name.
If the environment variable POSIXLY_CORRECT is set, 512-byte blocks
are used instead.
.TP
.I "\-t, \-\-sort=time"
Sort directory contents by timestamp instead of alphabetically, with
the newest files listed first.
.TP
.I "\-u, \-\-time=atime, \-\-time=access, \-\-time=use"
Sort directory contents according to the files' last access time
instead of the modification time.  If the long listing format is being
used, print the last access time instead of the modification time.
.TP
.I "\-x, \-\-format=across, \-\-format=horizontal"
List the files in columns, sorted horizontally.
.TP
.I "\-A, \-\-almost-all"
List all files in directories, except for `.' and `..'.
.TP
.I "\-B, \-\-ignore-backups"
Do not list files that end with `~', unless they are given on the
command line.
.TP
.I "\-C, \-\-format=vertical"
List files in columns, sorted vertically.
.TP
.I "\-F, \-\-classify"
Append a character to each file name indicating the file type.  For
regular files that are executable, append a `*'.  The file type
indicators are `/' for directories, `@' for symbolic links, `|' for
FIFOs, `=' for sockets, and nothing for regular files.
.TP
.I "\-G, \-\-no\-group"
Inhibit display of group information in a long format directory listing.
.TP
.I "\-L, \-\-dereference"
List the files linked to by symbolic links instead of listing the
contents of the links.
.TP
.I "\-N, \-\-literal"
Do not quote file names.
.TP
.I "\-Q, \-\-quote-name"
Enclose file names in double quotes and quote nongraphic characters as
in C.
.TP
.I "\-R, \-\-recursive"
List the contents of all directories recursively.
.TP
.I "\-S, \-\-sort=size"
Sort directory contents by file size instead of alphabetically, with
the largest files listed first.
.TP
.I "\-U, \-\-sort=none"
Do not sort directory contents; list them in whatever order they are
stored on the disk.  This option is not called
.I \-f
because the Unix
.B ls
.I \-f
option also enables
.I \-a
and disables
.IR \-l ,
.IR \-s ,
and
.IR \-t .
It seems useless and ugly to group those unrelated things together in
one option.  Since this option doesn't do that, it has a different
name.
.TP
.I "\-X, \-\-sort=extension"
Sort directory contents alphabetically by file extension (characters
after the last `.'); files with no extension are sorted first.
.TP
.I "\-1, \-\-format=single-column"
List one file per line.
.TP
.I "\-w, \-\-width cols"
Assume the screen is
.I cols
columns wide.  The default is taken from the terminal driver if
possible; otherwise the environment variable
.B COLUMNS
is used if it is set; otherwise the default is 80.
.TP
.I "\-T, \-\-tabsize cols"
Assume that each tabstop is
.I cols
columns wide.  The default is 8.
.TP
.I "\-I, \-\-ignore pattern"
Do not list files whose names match the shell pattern
.I pattern
unless they are given on the command line.  As in the shell, an
initial `.' in a filename does not match a wildcard at the start of
.I pattern.
.TP
.I "\-\-color, \-\-colour, \-\-color=yes, \-\-colour=yes"
Colorize the names of files depending on the type of file.
See
.B DISPLAY COLORIZATION
below.
.TP
.I "\-\-color=tty, \-\-colour=tty"
Same as
.I \-\-color
but only if standard output is a terminal.  This is very useful for
shell scripts and command aliases, especially if your favorite pager
does not support color control codes.
.TP
.I "\-\-color=no, \-\-colour=no"
Disables colorization.  This is the default.  Provided to override a
previous color option.
.TP
.I "\-\-help"
Print a usage message on standard output and exit successfully.
.TP
.I "\-\-version"
Print version information on standard output then exit successfully.
.SS DISPLAY COLORIZATION
When using the
.I "\-\-color"
option, this version of
.B ls
will colorize the file names printed according to the name and type of
file.  By default, this colorization is by type only, and the codes
used are ISO 6429 (ANSI) compliant.
.PP
You can override the default colors by defining the environment
variable
.B LS_COLORS
(or
.BR LS_COLOURS ).
The format of this variable is reminicent of the termcap(5) file
format; a colon-separated list of expressions of the form "xx=string",
where "xx" is a two-character variable name.  The variables with their
associated defaults are:
.sp
.RS +.2i
.ta 1.0i 2.5i
.nf
\fBno\fR       0       Normal (non-filename) text
\fBfi\fR       0       Regular file
\fBdi\fR       32      Directory
\fBln\fR       36      Symbolic link
\fBpi\fR       31      Named pipe (FIFO)
\fBso\fR       33      Socket
\fBbd\fR       44;37   Block device
\fBcd\fR       44;37   Character device
\fBex\fR       35      Executable file
\fBmi\fR       (none)  Missing file (defaults to fi)
\fBor\fR       (none)  Orphanned symbolic link (defaults to ln)
\fBlc\fR       \ee[    Left code
\fBrc\fR       m       Right code
\fBec\fR       (none)  End code (replaces lc+no+rc)
.fi
.RE
.sp
You only need to include the variables you want to change from the
default.
.PP
File names can also be colorized based on filename extension.  This is
specified in the LS_COLORS variable using the syntax "*ext=string".
For example, using ISO 6429 codes, to color all C-language source
files blue you would specify "*.c=34".  This would color all files
ending in .c in blue (34) color.
.PP
Control characters can be written either in C-style \e-escaped
notation, or in
.BR stty -like
^-notation.  The C-style notation adds \ee for Escape, \e_ for a
normal space characer, and \e? for Delete.  In addition, the \e escape
character can be used to override the default interpretation of \e, ^,
: and =.
.PP
Each file will be written as <lc> <color\ code> <rc> <filename> <ec>.
If the <ec> code is undefined, the sequence <lc> <no> <rc> will be
used instead.  This is generally more convenient to use, but less
general.  The left, right and end codes are provided so you don't have
to type common parts over and over again and to support weird
terminals; you will generally not need to change them at all unless
your terminal does not use ISO 6429 color sequences but a different
system.
.PP
If your terminal does use ISO 6429 color codes, you can compose the type
codes (i.e. all except the
.BR lc ,
.BR rc ,
and
.B ec
codes) from numerical commands separated by semicolons.  The most
common commands are:
.sp
.RS +.2i
.ta 1.0i
.nf
 0     to restore default color
 1     for brighter colors
 4     for underlined text
 5     for flashing text
30     for black foreground
31     for red foreground
32     for green foreground
33     for yellow (or brown) foreground
34     for blue foreground
35     for purple foreground
36     for cyan foreground
37     for white (or gray) foreground
40     for black background
41     for red background
42     for green background
43     for yellow (or brown) background
44     for blue background
45     for purple background
46     for cyan background
47     for white (or gray) background
.fi
.RE
.sp
Not all commands will work on all systems or display devices.
.PP
A few terminal programs do not recognize the default end code
properly.  If all text gets colorized after you do a directory
listing, try changing the
.B no
and
.B fi
codes from 0 to the numerical codes for your standard fore- and
background colors.
.SH BUGS
On BSD systems, the
.I \-s
option reports sizes that are half the correct values for files that
are NFS-mounted from HP-UX systems.  On HP-UX systems, it reports
sizes that are twice the correct values for files that are NFS-mounted
from BSD systems.  This is due to a flaw in HP-UX; it also affects the
HP-UX
.B ls
program.
.PP
If there was a single standard for the English language it would not
be necessary to support redundant spellings.
